THE NUMBER CRUNCHER

                             By Glen Bredon

    This program provides the powerful number handling abilities of
 the most capable calculators, as well as their convenience of use.
 For quick numerical calculations, and for handling many types of
 numerical algorithms, it is unmatched.  It is also a splended
 tutorial device because of its advanced capabilities.

    The main features of the calculator are:

  1. It has a complex number mode as well as the usual real mode.

  2. It can do numerical integrations including complex line integrals.

  3. It is programmable, and its programs can be written and edited with
     the built-in editor.  Programs can also be stored to disk.

  4. It directly supports such functions as sin, cos, tan, arcsin,
     arccos, arctan, and the hyperbolic analogues of these.  It also
     supports exp, log, abs, powers, 1/x, real part, imaginary part,
     angle, square root, pi, and int.  All functions are supported by
     the complex mode.

  5. It operates in either degree or radian measure.

  6. It has 9 user definable functions, which can also be written and
     edited using the built-in editor.  There is also a provision for 9
     user supplied machine language routines.

  7. It has a command to display the registers in the hex floating point
     format.  This is a great convenience as well as an educational tool.

  8. It is capable of reading a text file for data.  This allows running
     several programs on the same data.  It also allows additions to the
     data without typing it all in again.  This ability greatly enhances
     its usefulness for statistical programs.

  9. It has a printer interface with formatting (print using) abilities.

 10. There are 144 memory registers (in 16 banks of 9 each) and 4 stack
     registers and a number of memory manipulation commands.

 11. It has a "step" mode for debugging and examining the workings of a
     program.

 12. It has resident "help" information accessible at any time.

 13. All keys are redefinable.

 14. It can plot functions on the high resolution screen, including
     polar and parametric equations.

 15. A number of programs are included to do such calculations as
     computing averages and standard deviations, doing linear regression
     and chi square calculations, finding the roots of a cubic polynomial
     (including the complex roots), finding the residue of a complex
     function, computing the area of a polygon, and more.
 GETTING FAMILIAR WITH THE CALCULATOR

    The calculator works with the "reverse polish" notation used by the
 most advanced calculators.  This is a very efficient and logical method
 of calculation that uses no parentheses.  (Indeed, in this calculator,
 parentheses have an entirely different meaning.)  This notation may
 require a little getting used to, but after a few minutes using it,
 its definite advantages will become clear and its operation will become
 quite natural.  Since all registers are shown on the screen, the
 operation of the calculator is easily and quickly learned, much more
 so than with calculators showing only the main register.

    The reverse polish method can be quickly summarized by saying that
 the operations (sin, exp, log, etc.) that operate on only one number,
 are performed as soon as the key is hit and are performed on the number
 held in the "X" (main) register.  Those operations (times, plus, etc.)
 which operate on two numbers, also are performed as soon as the key is
 hit and are performed on the X and Y registers, leaving the result in
 the X register.  In the latter case, the previous X and Y registers are
 lost, and the "stack" moves down.  (That is, the contents of Z are put
 in Y, those of T are put in Z and T retains its former value.)

    Let us go though a few simple operations to gain familiarity with
 the operation of the calculator.

    Example 1:  To multiply  73  by  231:

 (a)  Enter the number  73  by pressing the 7 and then the 3 key.
 (b)  Copy this to the Y register by pressing RETURN (sometimes referred
      to as the ENTER key).
 (c)  Enter the number 231 by pressing 2 then 3 then 1.
 (d)  Do the multiplication by pressing the  *  key.  (Note that the  *
      key need not be shifted, : does as well.  The same is true of the
      + and ; keys.)

    Example 2:  To compute 87*87*87:

 (a)  Enter the number 87.
 (b)  Copy it to the Y and Z registers by pressing RETURN twice.
 (c)  Multiply all three by pressing * twice.

    Example 3:  Compute successive integral powers of 2:

 (a)  Press the key 2.
 (b)  Copy it to Y, Z and T by pressing RETURN three times.
 (c)  Press * several times.  Each time produces the next power of 2.

    Example 4:  Compute (3*4)+7:

 (a)  Press 3.
 (b)  Press RETURN to copy 3 to Y.
 (c)  Press the 4 key.
 (d)  Press the * key.
 (e)  Press the 7 key.  (Note that the previous result is pushed up
      to the Y register when you do this.)
 (f)  Press the + key.


    Example 5:  Compute (3*4)+(7*8):

 (a)  Press 3.
 (b)  Press RETURN.
 (c)  Press 4.
 (d)  Press *.
 (e)  Press 7.  (Note that Y now contains 3*4 and X contains 7.)
 (f)  Press RETURN to move the contents of Y to Z and to copy X to Y.
 (g)  Press 8.  (Now X has 8, Y has 7, Z has 3*4.)
 (h)  Press *.  (Now X has 8*7 and Y has 3*4.)
 (i)  Press + to get the final answer.

    Example 6:  Compute  2*EXP(2):

 (a)  Press 2.
 (b)  Press return to copy it to Y.
 (c)  Press the E key to get EXP(2).
 (d)  Press * for the final result.

    Example 7:  Compute  2*LOG(3*SQR(4*4+5))

 (a)  Press 5.  (One computes from the inside out.)
 (b)  Press RETURN.
 (c)  Press 4.
 (d)  Press RETURN to copy 4 to Y and to push 5 to Z.
 (e)  Press * to compute 4*4 in X and pull 5 down to Y.
 (f)  Press + to add 4*4 to 5.
 (g)  Press Q to compute the square root.
 (h)  Press 3 which will automatically push the previous result to Y.
 (i)  Press *.
 (j)  Press L to compute the logarithm (natural).
 (k)  Press 2.
 (l)  Press * for the final result.

    Example 8:  Compute ARCSIN(.5)/PI in radians:

 (a)  If "RAD" is not showing in upper case then press %.
 (b)  Press the . key then 5.
 (c)  Press A then S to get the ARCSIN.
      (Note that after pressing A only S, C, T, or H will be accepted.
      If you typed A then H then S then ARGSINH(.5) would result.)
 (d)  Press P to get PI and to push the previous result up.
 (e)  Press / to divide for the final answer.

    Example 9:  Compute the square of SIN(30 degrees):

 (a)  Press the % key if needed to make "DEG" show on the screen.
 (b)  Press 3 then 0.
 (c)  Press S to compute the SIN.
 (d)  Press RETURN to copy the result to Y.
 (e)  Press * to multiply it by itself.

 GENERAL DESCRIPTION OF OPERATION

    As indicated by the examples, there are certain times when an
 automatic "enter" is performed when you start a numerical entry (or
 PI or a memory recall).  The question arises as to when this happens
 and when it does not.  The answer is that the auto-enter is done when
 the previous operation is such that there would be no reason for it
 having been made if its result is not desired.  More precisely, an
 auto-enter is done when one starts numerical input or PI or a memory
 recall after any function (sin, log, etc.) or arithmetic operation
 (*, +, etc.) or any user defined function (Y followed by 1-9) or a
 memory recall (R followed by 1-9).  An auto enter is NOT done
 following a memory store (M followed by 1-9), an ENTER (RETURN key),
 a stack operation (U, D, X), or a register clear (control X).
 The mode change keys (%, $, #, J, cntr Z), the increase or decrease
 memory keys (<, >), and the keys used for programming instructions do
 not affect the status of the auto enter.  When in doubt, of course,
 one should just press the RETURN key to do the "enter" manually, or,
 if an enter is not desired, just use control X which clears the  X
 register and turns off any auto enter.

    The effect on the stack of any function of one argument (sin, exp,
 1/x, etc.) is simply that the operation is performed on the X register
 and the other registers are not affected.  This is also the case for
 a user defined function, even if it makes use of other registers.
 Operations which require two arguments (*, +, ^, etc.) place the result
 in the X register, destroy the Y register, move Z to Y, T to Z and
 retain the T register.  This is also the case with an integration, even
 though the function being integrated requires use of other registers.

    Key M followed by 1-9 copies the X register to the specified memory
 register.  Key R followed by 1-9 recalls the specified memory register
 to the X register (after performing an auto enter if the previous
 operation calls for one).  Key ^A followed by 1-9 adds the X register
 to the specified memory register.

    Radian or degree mode can be toggled by the % key.  In complex mode
 only the radian measure is supported and a switch (control Z) to complex
 mode automatically brings up radian measure mode.  Radian measure is
 automatically selected upon running or stepping a program.

    Hex mode, produced by key $, causes the registers to be displayed in
 their exact 5 byte floating point hex format, just as they are stored
 in memory.  This is a great facility for studying how Applesoft basic
 handles floating point numbers.  Hex mode does not affect numeric input
 which is always done in decimal form.  Key # switches back to decimal
 display.

    Since the E key is the EXP function and the - key is the subtract
 function, other keys must be used to produce the - and E characters
 for numeric input.  These are the keys _ and W.  Note that the negate
 key is convenient for inputting a negative number, however.



 CONFIGURATION

    The ProDOS startup convention is used to send an initialization
 string to the printer for use by the register printing commands
 (only accessible by calculator programs).  This is not used for
 program listing from the editor.  For the latter purpose, the editor
 provides a PR# type function that can be accessed from the editor
 itself.  If the STARTUP (at relative position 6 in the CALC file)
 is empty then the printer setup is ignored.  Otherwise you are asked
 if you want printer output (note you only get output if the particular
 calculator program has printer output instructions).  If you type "Y"
 then you are asked to turn on the printer and hit RETURN.  Upon doing
 this, the printer initialization string is sent to the printer.
 In this string the character "^" is an instruction to interpret the
 next character as a control character.  Two examples of common
 printer initialization strings are

        ^M        (just a return)
        ^I80N


 EXIT FROM THE CALCULATOR

    Exit can be made at any time by hitting RESET.  There is also an exit
 provision from the HELP menu.  These exit via the ProDOS quit command.
 Thus, if you are using a program selector like PROSEL, these will return
 to the selector.

 LOADING AND SAVING PROGRAMS

    The L and S commands on the help menu are for loading and saving of
 calculator programs.  Typing them will do a CATALOG and then ask for the
 program name.  The name extension (.PRG) is supplied by the computer,
 you don't type it.  The catalog can be "stopped" by typing control C.
 


 NUMERICAL INPUT

    When the word DATA is displayed at the lower left of the screen,
 the calculator is expecting numeric input.  This ordinarily happens
 when a program is running that wants input from the keyboard.  It can
 be brought up in immediate mode, however, simply by pressing the ESCAPE
 key.  When DATA is showing, the memory and stack operations are not
 available and, similarly, the two-register functions cannot be used.
 You may type a number, use a single argument function, or combinations
 of these.  (To input PI, for example, just press P.)  The input is
 terminated by the ESCAPE key or the RETURN key, which, in this mode,
 is no longer an ENTER!  In this mode the - key and the E key just
 give those characters.  (It is possible to perform an EXP function in
 this mode by using the @ key.)  When input is terminated by ESCAPE or
 RETURN the word DATA will disappear from the screen and two bells will
 sound.  (One bell sounds when the first ESCAPE is pressed.)

 Example: Input  -1.34E-12

 Method 1: type _1.34W_12
 Method 2: type ESC (if DATA is not showing) then -1.34E-12 RETURN
 Method 3: type 1.34W_12N
 Method 4: type ESC (if DATA is not showing) then 1.34E-12N RETURN


 DEGREE/RADIAN MODES

    Key % switches between these modes.  The only things affected by the
 status of this mode are the trigonometric functions sin, cos, tan,
 arcsin, arccos and arctan.  A switch to complex mode automatically
 selects radian mode and a switch to degree mode cannot be done when in
 complex mode.  Running a program automatically selects radian measure
 so programs intended for degree mode should start with "%".

 HELP PROVISIONS

    At any time, even when a program is requesting input, you can read
 the help information or you can even list the program that is in memory
 without affecting the status of the program or the registers.  To do
 this, simply type the help command "?".  This leads to the help menu
 from which several disk commands can be issued as well as the help
 listing and entry to the program editor.  The help listing describes
 the action of all active keys.  To return to the calculator from the
 help menu just type Q for "quit".
 COMPLEX MODE

    The control Z key toggles complex mode.  When in this mode, the
 display of imaginary parts can be toggled with the J key.  Real parts
 are shown as normal text, while the imaginary parts are in inverse
 text.  If a "+" is displayed to the right of a number then the other
 part of the number is nonzero.  For technical reasons, the degree mode
 is not available when in complex mode.  All functions are supported by
 complex mode.  (For example, try the square root or log of -1.)
 Running a program automatically sets real mode.  Thus a program that
 is to use complex mode must start with the control Z command.  The
 program will also default to real part display and should keep track of
 the status of this display if unexpected results are to be avoided.
 To input a number in complex mode just type the real or imaginary part,
 whichever is showing, then J then the other part.  Usually the entry of
 a number will automatically zero the opposite part, so it may not be
 necessary to do that manually.

    Since complex mode entails significantly more internal calculations
 than does real mode, you should expect slower operation and slightly
 less accurate computations.

    In complex mode, integrations (see the section on definite integrals)
 are done along the line joining the contents of the X and Y registers.
 By piecing together such segments, more complicated line integrals can
 be done.  (See the program RESIDUE.PRG.)

 PROGRAMMING

    A program can be entered into memory either from the calculator
 or from the editor.  The latter is to be preferred for complicated
 programs, but in the former case you can see what is happening to the
 registers.

    The command to begin entry of a program is control P.  (From the
 editor, however, you just type A for add.)  You must end entry of a
 program with a control E.  In between the control P and control E
 just type any sequence of operations you want performed by the program.
 If you want the program to pause for user input then press the escape
 key.  If you are writing the program from calculator mode rather than
 from the editor then you can type any number at this point (while the
 word DATA is displayed) and this will NOT go into the program.  To
 terminate the data entry and continue writing the program, press the
 escape again or the return key.

    To write a looping segment into a program, type a control W (for
 "while"), followed by -, #, or + (indicating while negative, while
 nonzero, and while positive or zero).  The loop segment must be
 terminated by a control L followed by specification of a memory
 register 1-9.  When the program is running, the loop will continue
 while the specified condition holds for the specified memory register,
 or until a "skip" command (the right arrow, control U) is pressed by
 the user in place of a numerical input.  Note that the decrement memory
 command can be used to do a loop with an explicit number of steps.

    Looping segments can be nested up to about 32 levels.
    A \ key followed by -,#, or + puts an IF condition in the program
 This causes a skip to the next ELSE or ENDIF if the X register is
 non-negative, zero, or negative, respectively.  An ELSE is provided
 by the control V key and reverses the IF condition.  An ENDIF is given
 by control Q.

    For example, to write a program which will get input from the user
 and then compute xsin(x), where x is the input, just type the sequence
 of keys  ^P ESC 1 ESC RETURN S * ^E.  (From the editor, you would type
 "D1," to first delete a program in memory, then "A RETURN" to go to the
 add mode, then ESC RETURN S * ^E.)

    For another example, to write a program which would select complex
 mode, get input, and compute log(sin(x)) of the input, just type
 ^P ^Z ESC ESC S L ^E.  Note that an error will be displayed as soon as
 you type the L if the X register contains 0.  This will not affect
 the program being entered, but if you want to avoid this you could
 type any number between the two escapes.

    Note that you can go to the editor at any time to modify or expand
 your program.


 RUNNING A PROGRAM

    Typing a control R will run the program in memory.  In order to
 increase speed (by a factor of 60 or so) the registers are not displayed
 when a program is running.  If the program stops and displays the word
 DATA at the lower left then it is expecting numerical input.  The input
 should be done as described under "NUMERICAL INPUT" and terminated with
 either an ESC or a RETURN.  Some programs will loop forever if they
 expect an indeterminate amount of data input.  (For example, a program
 to average a list of numbers input by the user.)  Such programs should
 be terminated with the right arrow key which causes the current loop to
 be skipped.  (Some programs may have more than one of these.)

    You can also "step" a program by issuing control S instead of
 control R.  In this case the registers are displayed at each step.
 Each step waits for a keypress to continue.  In addition, the operation
 to be processed next is indicated at the lower right.  In this
 indication, control characters are shown in inverse.  The inverse
 hyperbolic functions are indicated by a lower case "a" which will show
 up as an exclamation mark if the computer does not have a lower case
 adaptor.  Otherwise the command is shown by the key or key sequence used
 to issue the command.

    A program can be run with register display by using the step command
 and then holding down the space bar and repeat keys.  Stepping is
 invaluable for debugging a program.

    At any time a running or stepping program can be aborted with the
 control E (end) command.

    During program execution the ^R and ^S keys can be used to switch
 between the RUN and STEP modes.


 USING DATAFILES

    For some types of programs, particularly statistical ones, you may
 want to run the program on a list of data without having to type the
 data in every time.  For this, there is a provision for the access by
 a program of a text file for numerical input rather than input from
 the keyboard.  The text file, called here a datafile, must have a name
 which ends with ".DATA".  It must be opened by going to the help menu
 and typing the O command and then giving the name of the datafile.
 At this point you will be returned to the calculator and the name of
 the datafile will be displayed at the top of the screen after the name
 of the last loaded program.  Then you should type control R to run the
 program.  When the program first pauses for input, just type control D
 instead and the program will proceed to read input from the open file.
 At the end of the program, the file will be closed and will have to be
 reopened to be used again.  If the program expects termination by the
 right arrow "skip" command, then the datafile should end with that
 character.  If the file reaches its end before the program ends and
 does not have the proper skip, you will see "Hit a key" at the bottom
 of the screen.  When a key is hit, you will be sent to the help menu.
 At that point you can return to the calculator and type control E to
 abort the program, or you can open another datafile.  In the latter
 case, the program will continue operation with the new datafile.
 (This is automatic.)  Thus, datafiles can be chained in this manner.

    Datafiles can be written by a basic program or by a text editor such
 as the MERLIN assembler.  Commas may be used to separate data in a
 datafile as well as carriage returns.  The calculator interprets commas
 and carriage returns equivalently when read from a datafile.


 USING THE EDITOR

    Typing E from the help menu, sends you to the editor.  There you can
 do various things.  For example the program in memory can be listed by
 the L command.  L10,20 will list lines 10 to 20, L10, will list line 10
 to the end, etc.  The listing can be paused by hitting the space bar,
 and then stepped by repeated hittings of the space bar.  The listing is
 aborted by control C or key /.  Any other key restarts the listing.
 A listing can be sent to a printer by typing a P(slot #) command, any
 required initialization string and then the list command (each of these
 must be terminated by a carriage return).  P0 will turn the printer
 interface off again as will a return to the help menu by the Q command.

    You may delete any range of lines and may insert or add new ones.
 Note that "D1, <RTN>" will delete the entire program.  Any insertion or
 addition must be terminated by a control E (for end).  This important
 character should be remembered at all times.  It is used to end a
 program, end programming commands, end insertion of lines, etc.

    From the editor you can also access key redefinition.  See the
 section describing that option.
 NUMERICAL INTEGRATION

    The calculator has a built in facility for doing numerical definite
 integrals.  The algorithm used is Simpson's rule with 128 subdivisions.
 In most cases the accuracy is quite good.  To do a numerical integration
 from the keyboard, you must write a short program segment that starts
 with "(", which is the signal for start of integration, then contains
 the function to be integrated, then ends with ")", meaning end of
 integral.  The function inside the parentheses should be thought of as
 acting on the contents of the X register and terminating with the value
 of the function in the X register.  (For example the "function" RETURN
 RETURN * * is the cube function, and the integration program written
 by the key sequence  ^P ( RETURN RETURN * * ) ^E  will represent the
 integral of X*X*X.

    To perform the integration, once the program segment has been
 entered, you just place the left end point in the X register, the
 right end point in the Y register and run the program.  Thus, to
 integrate X*X*X from 3 to 5, you would enter the program segment shown
 above, then type 5 RETURN 3 ^R.

    Integrations may also be performed in complex mode.  There is no
 difference except that the "program" must begin with ^Z to turn on
 complex mode.  Also, of course, more time will be required for the
 computations to be performed in this mode.  By putting together
 several integrations in a program, one can integrate over any polygonal
 path in the complex plane.  See, for example, the program RESIDUE.PRG
 which does an integration along a diamond shaped path about the origin.

    In the real mode only there is a provision for precision integration.
 This is an "adaptive iterative routine" which continues to subdivide
 the interval until the numerical approximation becomes stable within
 a specified tolerance.

    The command for this mode is simply two integral "(" commands in
 a row.  (It is also suggested that the end of integral command ")"
 be doubled so that the editor listing will have the correct tabbing.
 This is not required, however.)  On entry to a precision integration,
 the T register should contain the desired tolerance.  If this is zero,
 or if it is less than the calculator deems appropriate, then the
 calculator will choose a tolerance automatically, usually 1E-6.
 On completion of the integration, this T register will have dropped
 into the Z register and the T register will contain the estimated
 maximum error in the result.  Note that the actual precision of the
 result will usually be better than shown by the tolerance in the T
 register, often by two decimal places or more.  This is because the
 tolerance represents a worst case estimate.

    The precision mode is recommended when the function is very wiggly
 such as those involved in computing the higher Fourier coefficients of
 a function.  The tolerance should not be taken too small, since this
 causes longer runs.  Usually a tolerance of 1E-4 works well.
 An OUT OF MEMORY error will indicate that the integration "stack"
 has overflowed and the integral cannot be computed within the
 specified tolerance.